Extend check-env-docs to catch missing sidebar and catalog entries - #1024
Open
sergiopaniego wants to merge 1 commit into
Open
Extend check-env-docs to catch missing sidebar and catalog entries#1024sergiopaniego wants to merge 1 commit into
sergiopaniego wants to merge 1 commit into
Conversation
|
The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
check-env-docsonly validates the per-env doc stubs. The docs sidebar (_toctree.yml) and the HTML catalog (environments.md) are maintained by hand, so forgetting them passes CI silently:qed_mathhas been missing its catalog card on main, and #1003 repeated the same pattern withlatex_ocr. This PR extendssync_env_docs.py --checkto fail when a stub is not listed in the sidebar or the catalog, and adds the missing QED Math card.Type of Change
Alignment Checklist
Before submitting, verify:
.claude/docs/PRINCIPLES.mdand this PR aligns with our principles.claude/docs/INVARIANTS.mdand no invariants are violated/pre-submit-pr(orbash .claude/hooks/lint.shand tests) and addressed all issuesRFC Status
Test Plan
python scripts/sync_env_docs.py --checkpasses on this branch (the new QED Math card closes the only existing gap).environments/<slug>link fromenvironments.md(or its- local:entry from_toctree.yml) makes--checkexit 1 with a message pointing at the missing entry and how to add it.--fix/--dry-runstill only write stub files. They now print a manual reminder for missing sidebar/catalog entries, including stubs--fixjust created, since the card content needs a human-written description.ruff checkclean on the script.Claude Code Review
Reviewed inline: the new
find_unlisted()is read-only, check semantics are unchanged for existing failure modes, and CI wiring (.github/workflows/test.yml) needs no changes since it already runs--check.Note
Low Risk
Documentation and CI validation only; no application runtime or security-sensitive code paths change.
Overview
sync_env_docs.py --checknow fails CI when an environment doc stub exists but is missing fromdocs/source/_toctree.yml(sidebar) ordocs/source/environments.md(HTML catalog). A newfind_unlisted()step scans those files; orphaned stubs are skipped.--fixstill only writes stub files but prints reminders to add sidebar/catalog entries manually, including slugs it just created.environments.mdgains a QED Math catalog card forqed_math, closing a gap that previously passed the old check.Reviewed by Cursor Bugbot for commit 1fb49b8. Bugbot is set up for automated code reviews on this repo. Configure here.